Apple WWDC 1996

home *** CD-ROM | disk | FTP | other *** search

/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Framework / Includes / UCommand.h < prev next >

Wrap

Text File | 1996-04-03 | 15.0 KB | 441 lines | [TEXT/MPS ]

// UCommand.h // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved. #ifndef __UCOMMAND__ #define __UCOMMAND__ // MacApp #ifndef __UEVENT__ #include "UEvent.h" #endif // #ifndef __UGEOMETRY__ // #include "UGeometry.h" // #endif // Toolbox #ifndef __APPLEEVENTS__ #include <AppleEvents.h> #endif //---------------------------------------------------------------------------------------- // Forward and external class declarations. //---------------------------------------------------------------------------------------- class TAppleEvent; class TCommand; class TCommandHandler; // class TScroller; class TView; //---------------------------------------------------------------------------------------- // Some typedefs //---------------------------------------------------------------------------------------- typedef EventPriority CommandPriority; //---------------------------------------------------------------------------------------- // Some constants //---------------------------------------------------------------------------------------- const Boolean kCanUndo = TRUE; const Boolean kCantUndo = FALSE; const Boolean kCausesChange = TRUE; const Boolean kDoesNotCauseChange = FALSE; // enum ELinkIdentity // { // kNotLinked, // kPrimary, // kSecondary // }; //---------------------------------------------------------------------------------------- // Global Function Prototypes //---------------------------------------------------------------------------------------- TCommand* CommitACommand(TCommand *aCommand); //---------------------------------------------------------------------------------------- // TCommand:Handles a user command, including undoing and mouse-tracking if required. // Usually created by the part of the Application with the greatest specific knowledge // about the action to take in response to events and passed back to be performed at // several well defined places. //---------------------------------------------------------------------------------------- class TCommand : public TEvent { MA_DECLARE_CLASS; public: TCommand(); // Empty constructor to satisfy compiler. //------------------------------------------------------------------------------------ // Init & Free //------------------------------------------------------------------------------------ void ICommand(CommandNumber itsCommandNumber, TCommandHandler* itsContext, Boolean canUndo, Boolean causesChange, TObject* objectToNotify); // Initialize a command procedurally. virtual ~TCommand(); // Frees fClipboardView and fUndoClipboardView when appropriate virtual void AbandonClipboardView(); // Frees fClipboardView when appropriate virtual void AbandonUndoClipboardView(); // Frees fUndoClipboardView when appropriate virtual void PrepareForUndoRedo(); // Make the command context visible for undo/redo. virtual void FinishUndoRedo(); // Common undo/redo code. virtual void RevealUndoRedo(); // Make this context visible after undo/redo. //------------------------------------------------------------------------------------ // command processing //------------------------------------------------------------------------------------ virtual void Process(); // override // Performs the command (instead of processing as an event). virtual Boolean NeedsToUnloadAllSegments(); // Default behavior is to return true // void LinkToSecondary(TCommand *secondaryCommand); // // Create a linked command pair with "this" as the primary command virtual void SetValidationError(OSErr validationError); // Set the validation state of this command virtual void Abort(); // Clean up after command fails. //------------------------------------------------------------------------------------ // command processing - usually overridden //------------------------------------------------------------------------------------ // virtual void Commit(); // // Stub virtual void DoIt(); // Stub virtual void RedoIt(); // Stub virtual void UndoIt(); // Stub virtual void DoNotification(); // Default calls fNotify->Changed if fCausesChange is true virtual void SetupDependencies(); // Undoable commands are dependents of their contexts. When // the context is changed, the command is committed. virtual void DoUpdate(ChangeID theChange, TObject* changedObject, TObject* changedBy, TDependencySpace* dependencySpace); // override // If the context closed, the command gets committed virtual void Completed(); // Called after the command's DoIt method has been called. Also called if // failure occurs during the process of DoIt, UndoIt, or RedoIt. //------------------------------------------------------------------------------------ // Clipboard handling //------------------------------------------------------------------------------------ virtual void ClaimClipboard(TView* clipboardView); // Installs the specified view in the clipboard window. Saves the current // clipboard view for purposes of Undo virtual void UndoRedoClipboard(); // Installs the appropriate view in the clipboard window //------------------------------------------------------------------------------------ // Scheduling //------------------------------------------------------------------------------------ virtual Boolean CanBeUndone(); // Default behavior is to return the value stored in fCanUndo virtual Boolean IsReadyToExecute(); // Returns true (the Default) when the command is ready to execute. Override to // base the execution of the command on more sophisticated criteria. Most programs // won't have to mess with this.. virtual Boolean ShouldFreeOnCompletion(); // Overridden to return the value stored in fFreeOnCompletion virtual Boolean IsRecurring(); // Overridden to return the value stored in fRecurring virtual Boolean WillCauseChange(); // Default behavior is to return the value stored in fCausesChange virtual TAppleEvent* MakeAppleEvent(); // Make an Apple Event corresponding to the command. Override for your commands. //------------------------------------------------------------------------------------ // Change notification //------------------------------------------------------------------------------------ virtual ChangeID GetChangeID(); // Returns a ChangeID for TApplication::PerformCommand to pass to Changed. Returns // fIdentifier as a default. //------------------------------------------------------------------------------------ // data members //------------------------------------------------------------------------------------ public: TObject* fObjectToNotify; // object to notify of changes TCommandHandler* fContext; // A document or view. If the command is // undoable it will be committed when the // context is closed TView* fClipboardView; // The view installed in the clipboard by this // command in its DoIt and RedoIt phases TView* fUndoClipboardView; // The view installed in the clipboard by this // command in its UndoIt phase TCommandHandler* fUndoClipboardViewContext; // The context of the command which originally // placed the current saved fUndoClipboardView // in the clipboard window OSErr fValidationError; // noErr (the default) indicates that neither // this command nor a linked command have // failed. // TCommand* fLinkedCommand; // Associated command that does and undoes in synch. // // Used by drag and drop. // ELinkIdentity fLinkIdentity; // Identifies command as unlinked or as the primary // // or secondary command in a command pair. Boolean fCommandDone; // "Done" as in DoIt/UndoIt/RedoIt. Boolean fCanUndo; // Defaults to true Boolean fCausesChange; // Defaults to true; Marks document // changed when command is done Boolean fFreeOnCompletion; // True to cause the command to be freed // on completion (the default). Completion // is after DoIt for non-undoable commands // and Commit for undoable commands. Boolean fReadyToExecute; // True (the default) will enable this // command to be returned from any queues // that may be holding it. Most programs // won't have to mess with this. Boolean fRecurring; // False (the default) will enable this // command to be removed from any command // queue that holds it because it is only // executed once. Boolean fUseAppleEvent; // True if the command should be handled by // sending an Apple Event Boolean fChangesClipboard; // Defaults to false. Set to true for // command subclasses representing CUT and/ // or COPY commands which change the // Clipboard. }; //---------------------------------------------------------------------------------------- // TAppleCommand: Abstract class for TServerCommand and TClientCommand. //---------------------------------------------------------------------------------------- class TAppleCommand : public TCommand { MA_DECLARE_CLASS; public: TAppleCommand(); // Constructor void IAppleCommand(CommandNumber itsCommandNumber, TCommandHandler* itsContext, Boolean canUndo, Boolean causesChange, TObject* objectToNotify); void IAppleCommand(CommandNumber itsCommandNumber, TCommandHandler* itsContext, Boolean canUndo, Boolean causesChange, TObject* objectToNotify, TAppleEvent* message, TAppleEvent* reply); virtual ~TAppleCommand(); virtual void FreeTheMessage(); // Frees fMessage and fReply. //---------------------------------------------------------------------------------------- // data members //---------------------------------------------------------------------------------------- public: TAppleEvent* fMessage; TAppleEvent* fReply; }; //---------------------------------------------------------------------------------------- // TServerCommand: Should be used to service an AppleEvent. It should also be used for all // commands that can be invoked by an AppleEvent _OR_ some user event (DoMenuCommand). // A good example is the 'odoc' command. The 'odoc' command's DoIt method simply opens // a list of files. TServerCommand lets that list come from an AppleEvent or from some user // action. //---------------------------------------------------------------------------------------- class TServerCommand : public TAppleCommand { MA_DECLARE_CLASS; public: TServerCommand(); // Constructor virtual ~TServerCommand(); // Destructor void IServerCommand(CommandNumber itsCommandNumber, TCommandHandler* itsContext, Boolean canUndo, Boolean causesChange, TObject* objectToNotify); // Initialize a TServerCommand to function independently (no message // or reply). void IServerCommand(CommandNumber itsCommandNumber, TCommandHandler* itsContext, Boolean canUndo, Boolean causesChange, TObject* objectToNotify, const AppleEvent& itsMessage, const AppleEvent& itsReply); // Initialize a TServerCommand from Apple Events. void IServerCommand(CommandNumber itsCommandNumber, TCommandHandler* itsContext, Boolean canUndo, Boolean causesChange, TObject* objectToNotify, TAppleEvent* itsMessage, TAppleEvent*itsReply); // Initialize a TServerCommand from MacApp TAppleEvent objects. // Replaces the old InitializeFromAppleEvent method. virtual void Process(); // override // Check the state of fRequiresUserInteraction and call AEInteractWithUser // if necessary. Report any errors back to the AppleEvent manager. void ResumeAndFreeMessage(); // If the event has been suspended then resume it and free the message. virtual void SetValidationError(OSErr error); // Report any errors in the supplied reply. virtual void Completed(); // override // Called when the command's DoIt method has been called, and after commit // if undoable. Also called if failure ocurred during the process of doing // the command. Overridden to Resume the suspended AppleEvent. //---------------------------------------------------------------------------------------- // data members //---------------------------------------------------------------------------------------- public: Boolean fRequiresUserInteraction; // If true AEInteractWithUser will be called // before the command is processed Boolean fSuspendTheEvent; // If true AESuspendTheCurrentEvent will be // called before the command is processed protected: Boolean fReplySent; // Set to TRUE in completed if an fReply was sent. }; //---------------------------------------------------------------------------------------- // TClientCommand: can be used to send an AppleEvent. If the message is to be sent // kAENoReply then the default behavior is to send its fMessage in the DoIt Method. // kAEWaitReply will send the message and process the reply before being posted to // the event queue for normal command processing. kAEQueueReply will send the message // and then place itself in a pending queue until its matching reply is received. Then it // will process the reply and allow itself to be posted to the event queue for normal // processing. //---------------------------------------------------------------------------------------- class TClientCommand : public TAppleCommand { MA_DECLARE_CLASS; public: TClientCommand(); // Constructor virtual ~TClientCommand(); // Destructor void IClientCommand(CommandNumber itsCommandNumber, TCommandHandler* itsContext, Boolean canUndo, Boolean causesChange, TObject* objectToNotify, TAppleEvent* theMessage = NULL); virtual long GetReturnID(); // Return the return ID of fMessage. Used to match an incoming reply with // this command. virtual Boolean IsReadyToPost(); // override // check that message has been sent and the reply received before posting the // command to the event queue. virtual void ProcessReply(TAppleEvent* theReply); // Assign theReply to fReply. Optionally one could process the contents of the // reply here and assign them to local instance variables virtual TAppleEvent* SendMessage(); // Send the message stored in fMessage and return the message if one is returned virtual void DoIt(); // override // Default behavior for a kAENoReply message is to send the message // If your message is to be sent by WaitReply or QueueReply you should override // DoIt to do your own thing //---------------------------------------------------------------------------------------- // data members //---------------------------------------------------------------------------------------- public: Boolean fMessageSent; }; #endif // __UCOMMAND__